Add early cluster validation to prevent wasted build time in func deploy #3117

RayyanSeliya · 2025-10-19T14:33:55Z

Changes

🐛 Add early cluster validation to prevent wasted build time in func deploy
🧹 Improve error messages for cluster connection failures with actionable guidance

What Changed

func deploy now validates Kubernetes cluster connectivity before starting the container build process, preventing wasted time when the cluster is inaccessible.

Before:

Built container image first (2-5 minutes)
Then failed with confusing errors like "invalid run-image" or "context canceled"
Different errors depending on whether --build=false was used

After:

Validates cluster connection immediately (< 5 seconds)
Fails fast with clear, specific error messages
Consistent behavior regardless of build flags
Provides actionable guidance for each error type

Implementation

Added 2-layer error handling:

Layer 1 (pkg/functions/errors.go): Technical errors (ErrInvalidKubeconfig, ErrClusterNotAccessible)
Layer 2 (cmd/deploy.go): User-friendly CLI messages with examples

Detects three distinct error scenarios:

Invalid kubeconfig file path
Empty/no cluster configuration
Cluster unreachable (network, auth, down, etc.)

Testing

Tested all combinations:

✅ Invalid KUBECONFIG path (with/without build flags)
✅ Empty kubeconfig (with/without build flags)
✅ Unreachable cluster (with/without build flags)
✅ Cluster stopped after configuration (network error)
✅ Valid cluster with kind (success path)
✅ Unit tests pass (TestDeploy_ConfigPrecedence, etc.)

/kind bug

Fixes #3116

Release Note

`func deploy` now validates cluster connectivity before building, providing immediate feedback with clear error messages instead of wasting time on builds that will fail deployment.

knative-prow · 2025-10-19T14:34:02Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: RayyanSeliya
Once this PR has been reviewed and has the lgtm label, please assign jrangelramos for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

knative-prow · 2025-10-19T14:34:05Z

Hi @RayyanSeliya. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

codecov · 2025-10-19T14:40:25Z

Codecov Report

❌ Patch coverage is 12.16216% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.87%. Comparing base (c9d4c54) to head (0c72cf2).

Files with missing lines	Patch %	Lines
cmd/deploy.go	0.00%	38 Missing ⚠️
pkg/knative/deployer.go	24.00%	16 Missing and 3 partials ⚠️
pkg/knative/client.go	27.27%	4 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #3117       +/-   ##
===========================================
+ Coverage   46.71%   59.87%   +13.16%     
===========================================
  Files         134      134               
  Lines       13519    13590       +71     
===========================================
+ Hits         6315     8137     +1822     
+ Misses       6486     4475     -2011     
- Partials      718      978      +260

Flag	Coverage Δ
e2e-tests	`41.46% <12.16%> (?)`
integration-tests	`54.43% <12.16%> (?)`
unit-tests	`46.46% <0.00%> (-0.25%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

gauron99 · 2025-10-19T15:13:59Z

/ok-to-test

cmd/deploy.go

matejvasek · 2025-10-20T10:12:47Z

cmd/deploy.go


+// validateClusterConnection checks if the Kubernetes cluster is accessible before starting build
+func validateClusterConnection() error {
+	// Skip for test environments (check if using test kubeconfig)


I would prefer if we called our k8s.NewKubernetesClientset() and checked the err return value.
Also I do not like making the code "test aware". Could we think of something better?

Thxs for the feedback @matejvasek ! I've updated it to use k8s.NewKubernetesClientset() and check the error as you suggested. The /testdata/ check follows Go's convention for test fixtures , it catches cases where tests use stale kubeconfig paths. The .example.com check skips API calls for test/example clusters (RFC 2606 reserved domain).

gauron99 · 2025-10-21T15:34:35Z

Im not much of a fan of this implementation... its still "test aware" as Matej said - with those literal strings and constants. Also there has to be some better way to implement this 🤔
Maybe as a method of client Instance (in pkg/functions/client.go) ? Instance has its method "CurrentState" or "State" or "Available" or something like this?
@lkingland @matejvasek

RayyanSeliya · 2025-10-22T15:01:22Z

Im not much of a fan of this implementation... its still "test aware" as Matej said - with those literal strings and constants. Also there has to be some better way to implement this 🤔 Maybe as a method of client Instance (in pkg/functions/client.go) ? Instance has its method "CurrentState" or "State" or "Available" or something like this? @lkingland @matejvasek

@gauron99 Good point about the client architecture! I checked pkg/functions/client.go and saw it already has methods like Deploy(), Build(), etc.

I'm thinking we could add:

func (c *Client) ClusterAvailable(ctx context.Context) error

Then just call it before building. Tests would naturally skip it since they use NewTestClient() with mocks.

The challenge is timing - we currently validate before creating the client (line 423 vs line 462 in cmd/deploy.go's runDeploy()). We'd need to either:

Create the client earlier, or
Make it a standalone function like functions.ValidateCluster()

Which direction makes more sense for the existing code? Don't want to refactor the way which is not feasible ..!

@lkingland @matejvasek

lkingland · 2025-11-03T11:08:00Z

This one is a little tricky...
I understand the desire to validate in the CLI to "fail fast". But too much pre-validation creates a hard dependency between the CLI and the deployer.

I think it might be worth looking into placing this validation in the deployer implementation itself, returing a typed error on failure, and then capturing this error in the CLI and adding "CLI specific" help text as necessary.

Remember that it's ok if the system builds and then fails on deployment, because it should not repeat the build on a subsequent deploy (it detects the build is "fresh").

Signed-off-by: RayyanSeliya <[email protected]>

…er instead of too much pre-validation at the cli Signed-off-by: RayyanSeliya <[email protected]>

RayyanSeliya · 2025-11-05T16:17:53Z

This one is a little tricky... I understand the desire to validate in the CLI to "fail fast". But too much pre-validation creates a hard dependency between the CLI and the deployer.

I think it might be worth looking into placing this validation in the deployer implementation itself, returing a typed error on failure, and then capturing this error in the CLI and adding "CLI specific" help text as necessary.

Remember that it's ok if the system builds and then fails on deployment, because it should not repeat the build on a subsequent deploy (it detects the build is "fresh").

thx for the feedback @lkingland that makes sense and sounds good to have the validation into the deployer itself with typed errors and CLI just catches those and provide a user-friendly errors ! can have a look now and ping me if any more changes needed !

knative-prow bot added the kind/bug Categorizes issue or PR as related to a bug. label Oct 19, 2025

knative-prow bot requested review from dsimansk and jrangelramos October 19, 2025 14:34

knative-prow bot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Oct 19, 2025

knative-prow bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Oct 19, 2025

knative-prow bot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 19, 2025

gauron99 requested review from gauron99, lkingland and matejvasek and removed request for dsimansk and jrangelramos October 19, 2025 15:14

gauron99 reviewed Oct 19, 2025

View reviewed changes

cmd/deploy.go Outdated Show resolved Hide resolved

cmd/deploy.go Outdated Show resolved Hide resolved

matejvasek reviewed Oct 20, 2025

View reviewed changes

RayyanSeliya requested a review from gauron99 October 20, 2025 11:38

RayyanSeliya closed this Oct 22, 2025

RayyanSeliya reopened this Oct 22, 2025

RayyanSeliya added 5 commits November 5, 2025 17:58

Add early cluster validation to prevent wasted build time in func deploy

1893c2a

Signed-off-by: RayyanSeliya <[email protected]>

fix linting errors

83f56f0

Signed-off-by: RayyanSeliya <[email protected]>

refactor the code based on suggestion

bb2de7e

Signed-off-by: RayyanSeliya <[email protected]>

fix the linter issues

09e7c98

Signed-off-by: RayyanSeliya <[email protected]>

refactor based on the review to move the implementation at the deploy…

0c72cf2

…er instead of too much pre-validation at the cli Signed-off-by: RayyanSeliya <[email protected]>

RayyanSeliya force-pushed the cluster-errors-deploy branch from 02c38ab to 0c72cf2 Compare November 5, 2025 16:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add early cluster validation to prevent wasted build time in func deploy #3117

Add early cluster validation to prevent wasted build time in func deploy #3117

RayyanSeliya commented Oct 19, 2025

Uh oh!

knative-prow bot commented Oct 19, 2025

Uh oh!

knative-prow bot commented Oct 19, 2025

Uh oh!

codecov bot commented Oct 19, 2025 •

edited

Loading

Uh oh!

gauron99 commented Oct 19, 2025

Uh oh!

Uh oh!

Uh oh!

matejvasek Oct 20, 2025

Uh oh!

RayyanSeliya Oct 20, 2025 •

edited

Loading

Uh oh!

gauron99 commented Oct 21, 2025

Uh oh!

RayyanSeliya commented Oct 22, 2025

Uh oh!

lkingland commented Nov 3, 2025

Uh oh!

RayyanSeliya commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add early cluster validation to prevent wasted build time in func deploy #3117

Are you sure you want to change the base?

Add early cluster validation to prevent wasted build time in func deploy #3117

Conversation

RayyanSeliya commented Oct 19, 2025

Changes

What Changed

Implementation

Testing

Uh oh!

knative-prow bot commented Oct 19, 2025

Uh oh!

knative-prow bot commented Oct 19, 2025

Uh oh!

codecov bot commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gauron99 commented Oct 19, 2025

Uh oh!

Uh oh!

Uh oh!

matejvasek Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

RayyanSeliya Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gauron99 commented Oct 21, 2025

Uh oh!

RayyanSeliya commented Oct 22, 2025

Uh oh!

lkingland commented Nov 3, 2025

Uh oh!

RayyanSeliya commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Oct 19, 2025 •

edited

Loading

RayyanSeliya Oct 20, 2025 •

edited

Loading